React

SejHey provides a simple and efficient component and hook for integrating internationalization (i18n) into your React applications. It allows you to manage translations easily, whether you prefer static files or dynamic loading via a manifest URL, all compatible with your SejHey project.

Installation

Use npm to install the SejHey i18n package in your React project:

 npm i @sejhey/react-i18n

---

Reference

SejHeyProvider

The SejHeyProvider component is the main entry point for integrating SejHey i18n into your React application. It provides the context for translations and allows you to configure how translations are loaded.

Props:

• i18nOptions:

  • lng: Default language to use when the app loads. This should match one of the languages defined in your translations.

  • fallbackLng: Fallback language to use when a translation is missing in the current language. This is useful for ensuring that your app can still display content even if a translation is not available.

  • staticFiles: An object mapping language codes to functions that return the translation files. These files should be in the i18n JSON format and can be lazy-loaded. This is useful for smaller applications or when you want to bundle translations with your app.

  • manifestUrl: A URL to a SejHey manifest file that contains translations for multiple languages. This is useful for larger applications where you want to load translations dynamically. Remember to set the file type to i18n JSON (.json) in your SejHey project. If used, it will replace staticFiles.

    See example below for how to create a manifest URL in SejHey.

    

  • loader: A React component that will be displayed while translations are being loaded. This can be a simple loading spinner or any other component you prefer.

Usage Example

import { SejHeyProvider } from '@sejhey/react-i18n'
;<SejHeyProvider
  i18nOptions={{
    lng: 'en', //Defines the default language

    fallbackLng: 'en', //Default fallback language to show when a translation is missing

    //If you want to use static files, you can define them like this, they will automatically be lazy loaded once the user changes language
    //This is useful for smaller apps or when you want to bundle translations with your app
    staticFiles: {
      en: () => import('./locales/en.json'), //Can be exported from SejHey as i18n JSON files
      fr: () => import('./locales/fr.json')
    },

    //Instead of static files, you can use a manifest URL to load translations dynamically. The manifest URL should point to a SejHey manifest file.
    manifestUrl: 'https://cdn.sejhey.com/**PROJECT_ID**/manifest.json', //The file type for this must be set to i18n JSON (.json)

    loader: <div>Loading translations...</div> //Optional loader component to show while translations are being fetched
  }}
>
  <>{/*The rest of your content goes here*/}</>
</SejHeyProvider>

---

useTranslate Hook

The useTranslate hook provides a convenient way to access translations in your components. It returns an object with a t function that you can use to get translations by key. It also returns the current language, available locales, and a function to change the language.

Returned Object:

{
    t: (key: string) => string; 
    currentLanguage: string;
    changeLanguage: (lng: string) => Promise<void>;
    availableLocales: string[];
}

t

The translation function that takes a key and returns the translated string. You can also pass parameters to replace placeholders in the translation.

currentLanguage

The currently active language code.

changeLanguage

A function that allows you to change the current language. It takes a language code as an argument and returns a promise that resolves when the language is changed.

availableLocales

An array of available locales that can be used to populate a language selection dropdown.

Example Usage

import { useTranslate } from '@sejhey/react-i18n'

const MyComponent = () => {

  const { t, currentLanguage, changeLanguage, availableLocales } = useTranslate()

  return (
    <>
      <h1>{t('welcome_message')}</h1>

      {/* Change language dropdown */}
      <select
        style={{
          position: 'absolute',
          cursor: 'pointer',
          bottom: '10px',
          zIndex: 99,
          right: '10px'
        }}
        value={currentLanguage}
        onChange={e => onChangeLang(e.target.value)}
      >
        {availableLocales.map(({ locale }) => (
          <option key={locale} value={locale}>
            {locale}
          </option>
        ))}
      </select>
    </>
  )
}

---

T Component

The T component is a React component that allows you to render translations directly in your JSX. It takes a keyName prop for the translation key and optional params for dynamic values.

Props:

{
    keyName: string; // The translation key to look up
    params?: Record<string, any>; // Optional parameters to replace in the translation
    defaultValue?: string; // Optional fallback value if the translation is missing
}

keyName

The key for the translation you want to render.

params

An object containing parameters to replace placeholders in the translation string. For example, if your translation is "Hello, {{name}}!", you can pass { name: 'John' } to replace {{name}} with "John". If you are using pluralization, you can pass a count parameter to handle plural forms correctly.

defaultValue

An optional fallback value to use if the translation for the given key is missing. This can be useful for providing a default message or value when translations are not available.

Example Usage

import { T } from '@sejhey/react-i18n'

const MyComponent = () => {
  return (
    <div>
      {/* This will render "You have 3 unread messages" if the translation is set up correctly */}
      <T keyName='unread_messages' params={{ count: 3 }} />

      {/* This will render "Welcome, John!" if the translation is set up correctly */}
      <T keyName='welcome_name' params={{ name: 'John' }} />
    </div>
  )
}

More examples

Please see our Guide for a complete example of how to set up and use SejHey i18n in a React application.